.TH "Links (Spotify URIs)" 3spotify "Wed Mar 28 2012" "libspotify" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Links (Spotify URIs) \- 
.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBsp_linktype\fP { \fBSP_LINKTYPE_INVALID\fP =  0, \fBSP_LINKTYPE_TRACK\fP =  1, \fBSP_LINKTYPE_ALBUM\fP =  2, \fBSP_LINKTYPE_ARTIST\fP =  3, \fBSP_LINKTYPE_SEARCH\fP =  4, \fBSP_LINKTYPE_PLAYLIST\fP =  5, \fBSP_LINKTYPE_PROFILE\fP =  6, \fBSP_LINKTYPE_STARRED\fP =  7, \fBSP_LINKTYPE_LOCALTRACK\fP =  8, \fBSP_LINKTYPE_IMAGE\fP =  9 }"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_string\fP (const char *link)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_track\fP (\fBsp_track\fP *track, int offset)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_album\fP (\fBsp_album\fP *album)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_album_cover\fP (\fBsp_album\fP *album)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_artist\fP (\fBsp_artist\fP *artist)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_artist_portrait\fP (\fBsp_artist\fP *artist)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_artistbrowse_portrait\fP (\fBsp_artistbrowse\fP *arb, int index)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_search\fP (\fBsp_search\fP *search)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_playlist\fP (\fBsp_playlist\fP *playlist)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_user\fP (\fBsp_user\fP *user)"
.br
.ti -1c
.RI "\fBsp_link\fP * \fBsp_link_create_from_image\fP (\fBsp_image\fP *image)"
.br
.ti -1c
.RI "int \fBsp_link_as_string\fP (\fBsp_link\fP *link, char *buffer, int buffer_size)"
.br
.ti -1c
.RI "\fBsp_linktype\fP \fBsp_link_type\fP (\fBsp_link\fP *link)"
.br
.ti -1c
.RI "\fBsp_track\fP * \fBsp_link_as_track\fP (\fBsp_link\fP *link)"
.br
.ti -1c
.RI "\fBsp_track\fP * \fBsp_link_as_track_and_offset\fP (\fBsp_link\fP *link, int *offset)"
.br
.ti -1c
.RI "\fBsp_album\fP * \fBsp_link_as_album\fP (\fBsp_link\fP *link)"
.br
.ti -1c
.RI "\fBsp_artist\fP * \fBsp_link_as_artist\fP (\fBsp_link\fP *link)"
.br
.ti -1c
.RI "\fBsp_user\fP * \fBsp_link_as_user\fP (\fBsp_link\fP *link)"
.br
.ti -1c
.RI "void \fBsp_link_add_ref\fP (\fBsp_link\fP *link)"
.br
.ti -1c
.RI "void \fBsp_link_release\fP (\fBsp_link\fP *link)"
.br
.in -1c
.SH "Detailed Description"
.PP 
These functions handle links to Spotify entities in a way that allows you to not care about the textual representation of the link\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBsp_linktype\fP"
Link types 
.PP
\fBEnumerator: \fP
.in +1c
.TP
\fB\fISP_LINKTYPE_INVALID \fP\fP
Link type not valid - default until the library has parsed the link, or when parsing failed\&. 
.TP
\fB\fISP_LINKTYPE_TRACK \fP\fP
Link type is track\&. 
.TP
\fB\fISP_LINKTYPE_ALBUM \fP\fP
Link type is album\&. 
.TP
\fB\fISP_LINKTYPE_ARTIST \fP\fP
Link type is artist\&. 
.TP
\fB\fISP_LINKTYPE_SEARCH \fP\fP
Link type is search\&. 
.TP
\fB\fISP_LINKTYPE_PLAYLIST \fP\fP
Link type is playlist\&. 
.TP
\fB\fISP_LINKTYPE_PROFILE \fP\fP
Link type is profile\&. 
.TP
\fB\fISP_LINKTYPE_STARRED \fP\fP
Link type is starred\&. 
.TP
\fB\fISP_LINKTYPE_LOCALTRACK \fP\fP
Link type is a local file\&. 
.TP
\fB\fISP_LINKTYPE_IMAGE \fP\fP
Link type is an image\&. 
.SH "Function Documentation"
.PP 
.SS "void \fBsp_link_add_ref\fP (\fBsp_link\fP *link)"
Increase the reference count of a link
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP The link object 
.RE
.PP

.SS "\fBsp_album\fP* \fBsp_link_as_album\fP (\fBsp_link\fP *link)"
The album representation for the given link
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP The Spotify link whose album you are interested in
.RE
.PP
\fBReturns:\fP
.RS 4
The album representation of the given album link If the link is not of album type then NULL is returned 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBbrowse\&.c\fP\&.
.SS "\fBsp_artist\fP* \fBsp_link_as_artist\fP (\fBsp_link\fP *link)"
The artist representation for the given link
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP The Spotify link whose artist you are interested in
.RE
.PP
\fBReturns:\fP
.RS 4
The artist representation of the given link If the link is not of artist type then NULL is returned 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBbrowse\&.c\fP\&.
.SS "int \fBsp_link_as_string\fP (\fBsp_link\fP *link, char *buffer, intbuffer_size)"
Create a string representation of the given Spotify link
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP The Spotify link whose string representation you are interested in 
.br
\fIbuffer\fP The buffer to hold the string representation of link 
.br
\fIbuffer_size\fP The max size of the buffer that will hold the string representation The resulting string is guaranteed to always be null terminated if buffer_size > 0
.RE
.PP
\fBReturns:\fP
.RS 4
The number of characters in the string representation of the link\&. If this value is greater or equal than \fCbuffer_size\fP, output was truncated\&. 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBbrowse\&.c\fP, and \fBtoplist\&.c\fP\&.
.SS "\fBsp_track\fP* \fBsp_link_as_track\fP (\fBsp_link\fP *link)"
The track representation for the given link
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP The Spotify link whose track you are interested in
.RE
.PP
\fBReturns:\fP
.RS 4
The track representation of the given track link If the link is not of track type then NULL is returned\&. 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBbrowse\&.c\fP\&.
.SS "\fBsp_track\fP* \fBsp_link_as_track_and_offset\fP (\fBsp_link\fP *link, int *offset)"
The track and offset into track representation for the given link
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP The Spotify link whose track you are interested in 
.br
\fIoffset\fP Pointer to offset into track (in milliseconds)\&. If the link does not contain an offset this will be set to 0\&.
.RE
.PP
\fBReturns:\fP
.RS 4
The track representation of the given track link If the link is not of track type then NULL is returned\&. 
.RE
.PP

.SS "\fBsp_user\fP* \fBsp_link_as_user\fP (\fBsp_link\fP *link)"
The user representation for the given link
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP The Spotify link whose user you are interested in
.RE
.PP
\fBReturns:\fP
.RS 4
The user representation of the given link If the link is not of user type then NULL is returned 
.RE
.PP

.SS "\fBsp_link\fP* \fBsp_link_create_from_album\fP (\fBsp_album\fP *album)"
Create a link object from an album
.PP
\fBParameters:\fP
.RS 4
\fIalbum\fP An album object
.RE
.PP
\fBReturns:\fP
.RS 4
A link representing the album
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP 
.RE
.PP

.SS "\fBsp_link\fP* \fBsp_link_create_from_album_cover\fP (\fBsp_album\fP *album)"
Create an image link object from an album
.PP
\fBParameters:\fP
.RS 4
\fIalbum\fP An album object
.RE
.PP
\fBReturns:\fP
.RS 4
A link representing the album cover\&. Type is set to SP_LINKTYPE_IMAGE
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP 
.RE
.PP

.SS "\fBsp_link\fP* \fBsp_link_create_from_artist\fP (\fBsp_artist\fP *artist)"
Creates a link object from an artist
.PP
\fBParameters:\fP
.RS 4
\fIartist\fP An artist object
.RE
.PP
\fBReturns:\fP
.RS 4
A link object representing the artist
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP 
.RE
.PP

.SS "\fBsp_link\fP* \fBsp_link_create_from_artist_portrait\fP (\fBsp_artist\fP *artist)"
Creates a link object pointing to an artist portrait
.PP
\fBParameters:\fP
.RS 4
\fIartist\fP Artist browse object
.RE
.PP
\fBReturns:\fP
.RS 4
A link object representing an image
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP 
.PP
\fBsp_artistbrowse_num_portraits()\fP 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBtoplist\&.c\fP\&.
.SS "\fBsp_link\fP* \fBsp_link_create_from_artistbrowse_portrait\fP (\fBsp_artistbrowse\fP *arb, intindex)"
Creates a link object from an artist portrait
.PP
\fBParameters:\fP
.RS 4
\fIarb\fP Artist browse object 
.br
\fIindex\fP The index of the portrait\&. Should be in the interval [0, \fBsp_artistbrowse_num_portraits()\fP - 1]
.RE
.PP
\fBReturns:\fP
.RS 4
A link object representing an image
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP 
.PP
\fBsp_artistbrowse_num_portraits()\fP
.RE
.PP
\fBNote:\fP
.RS 4
The difference from \fBsp_link_create_from_artist_portrait()\fP is that the artist browse object may contain multiple portraits\&. 
.RE
.PP

.SS "\fBsp_link\fP* \fBsp_link_create_from_image\fP (\fBsp_image\fP *image)"
Create a link object representing the given image
.PP
\fBParameters:\fP
.RS 4
\fIimage\fP Image object
.RE
.PP
\fBReturns:\fP
.RS 4
A link representing the image\&.
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP 
.RE
.PP

.SS "\fBsp_link\fP* \fBsp_link_create_from_playlist\fP (\fBsp_playlist\fP *playlist)"
Create a link object representing the given playlist
.PP
\fBParameters:\fP
.RS 4
\fIplaylist\fP Playlist object
.RE
.PP
\fBReturns:\fP
.RS 4
A link representing the playlist
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP
.RE
.PP
\fBNote:\fP
.RS 4
Due to reasons in the playlist backend design and the Spotify URI scheme you need to wait for the playlist to be loaded before you can successfully construct an URI\&. If \fBsp_link_create_from_playlist()\fP returns NULL, try again after teh playlist_state_changed callback has fired\&. 
.RE
.PP

.SS "\fBsp_link\fP* \fBsp_link_create_from_search\fP (\fBsp_search\fP *search)"
Generate a link object representing the current search
.PP
\fBParameters:\fP
.RS 4
\fIsearch\fP Search object
.RE
.PP
\fBReturns:\fP
.RS 4
A link representing the search
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP 
.RE
.PP

.SS "\fBsp_link\fP* \fBsp_link_create_from_string\fP (const char *link)"
Create a Spotify link given a string
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP A string representation of a Spotify link
.RE
.PP
\fBReturns:\fP
.RS 4
A link representation of the given string representation\&. If the link could not be parsed, this function returns NULL\&.
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_type()\fP 
.PP
\fBsp_link_release()\fP 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBbrowse\&.c\fP\&.
.SS "\fBsp_link\fP* \fBsp_link_create_from_track\fP (\fBsp_track\fP *track, intoffset)"
Generates a link object from a track
.PP
\fBParameters:\fP
.RS 4
\fItrack\fP A track object 
.br
\fIoffset\fP Offset in track in ms\&.
.RE
.PP
\fBReturns:\fP
.RS 4
A link representing the track
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBbrowse\&.c\fP\&.
.SS "\fBsp_link\fP* \fBsp_link_create_from_user\fP (\fBsp_user\fP *user)"
Create a link object representing the given playlist
.PP
\fBParameters:\fP
.RS 4
\fIuser\fP User object
.RE
.PP
\fBReturns:\fP
.RS 4
A link representing the profile\&.
.RE
.PP
\fBNote:\fP
.RS 4
You need to release the link when you are done with it\&. 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBsp_link_release()\fP 
.RE
.PP

.SS "void \fBsp_link_release\fP (\fBsp_link\fP *link)"
Decrease the reference count of a link
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP The link object 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBbrowse\&.c\fP, and \fBtoplist\&.c\fP\&.
.SS "\fBsp_linktype\fP \fBsp_link_type\fP (\fBsp_link\fP *link)"
The link type of the specified link
.PP
\fBParameters:\fP
.RS 4
\fIlink\fP The Spotify link whose type you are interested in
.RE
.PP
\fBReturns:\fP
.RS 4
The link type of the specified link - see the sp_linktype enum for possible values 
.RE
.PP

.PP
\fBExamples: \fP
.in +1c
\fBbrowse\&.c\fP\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libspotify from the source code\&.
